<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <meta name="author" content="makumba-dev group">
  <title>Makumba quick start guide</title>
  <link rel="stylesheet" type="text/css" media="all" href="main.css">
  <script type="text/javascript" src="main.js"></script>
</head>
<body>
<script type="text/javascript">
   makeNavBar("");
</script>

<h1>Makumba quick start guide</h1>

<p>This is a quick guide to help you get <b>Makumba</b> up and running. In this document we will
show you how to deploy a simple <b>Makumba</b> application covering the following steps:</p>
<ol>
  <li><a href="#Installation">Installation</a></li>
  <li><a href="#Creating">Creating a basic application</a>
  <ul>
    <li><a href="#Folder">Folder structure</a></li>
    <li><a href="#Deploying">Deploying the libraries</a></li>
    <li><a href="#Configuration">Configuration files</a></li>
    <li><a href="#Data">Data definitions</a></li>
    <li><a href="#Example">Example application</a></li>
  </ul>
  </li>
</ol>

<h2><a name="Installation">&nbsp;</a>Installation</h2>

<p>So, you want to start building apps with <b>Makumba</b>? You're on the right track, now let's
make sure you have the right tools! This is what you need:</p>

<ul>
  <li><b>Makumba</b> - you can get it <a href="download.html">right here</a></li>
  <li><b>A JSP 2.0 compatible container</b> - we will assume you're using <a
    href="http://jakarta.apache.org/tomcat/">Tomcat 5.0</a> or higher but using another servlet
  container is possible, although the configuration might require some server-specific modifications</li>
  <li><b>A supported SQL engine</b> - we will assume you're using <a
    href="http://www.mysql.com/">MySQL</a> but a list of the supported SQL engines can be found
  <a href="SQL-drivers.html#intro">here</a></li>
  <li><b>A JDBC driver</b> - for MySQL you should use <a
    href="http://www.mysql.com/downloads/api-jdbc.html">MySQL Connector/J</a></li>
  <li><b>ANTLR</b> - <a href="http://www.antlr.org/">ANother Tool for Language Recognition</a>,
  (formerly PCCTS), necessary to translate database queries from and to OQL. The following table
  should help you get the correct ANTLR version for your <b>Makumba</b> library: <br />
  <br />
  <table class="tagParamDef">
    <tbody>
      <tr>
        <th>Makumba version</th>
        <th>Recommended ANTLR version</th>
      </tr>
      <tr>
        <td><tt>?.?.??.? - 0.5.13.8</tt></td>
        <td><tt><a href="http://www.antlr2.org/download/antlr-2.7.2.zip">2.7.2</a></tt></td>
      </tr>
    </tbody>
  </table>
  <br />
  </li>
</ul>

<h2><a name="Creating">&nbsp;</a>Creating a basic application</h2>

<p>Now that you've got the tools let's get them to work!</p>

<h3><a name="Folder">&nbsp;</a>Folder structure</h3>

<p>With <b>Tomcat</b> you deploy each application in a subfolder of <tt>webapps</tt>. We will
further on refer to this subfolder as the <i>root folder</i> of your application. This being a test,
let's name it <tt>maktest</tt>.</p>

<p>In order to be a valid web module, this root folder of your application should contain a <tt>WEB-INF</tt>
folder. This is where you should have your <tt>web.xml</tt> deployment descriptor and the <tt>classes</tt>
and <tt>lib</tt> folders.</p>

<p>This is how the folder structure is supposed to look like:</p>

<pre class="example">
maktest/
&nbsp;&nbsp;WEB-INF/
&nbsp;&nbsp;&nbsp;&nbsp;classes/
&nbsp;&nbsp;&nbsp;&nbsp;lib/
&nbsp;&nbsp;&nbsp;&nbsp;web.xml
</pre>

<h3><a name="Deploying">&nbsp;</a>Deploying the libraries</h3>

<p>In order for the libraries to be accessible they should be placed either in your <b>Tomcat</b>'s
<tt>/common/lib</tt> folder of in your application's <tt>/WEB-INF/lib</tt> folder.</p>

<p>Putting them in the <tt>/common/lib</tt> folder will make them accessible to all applications
deployed in the container but we recommend using the application-specific folder (at least for this
example).</p>

<div class="note">The libraries are in the form of .jar (Java archives). According to the
prerequisites you should have three of them:
<ul>
  <li><tt>makumba.jar</tt></li>
  <li><tt>antlr-?.?.?.jar</tt></li>
  <li><tt>mysql-connector-java-?.?.?-bin.jar</tt></li>
</ul>
</div>

<h3><a name="Configuration">&nbsp;</a>Configuration files</h3>

<p>Don't get too scared! There's very few of them:</p>
<ul>
  <li>the application deployment descriptor</li>
  <li>the makumba database configuration files</li>
</ul>

<h4>&nbsp;Deployment descriptor</h4>

<p>This is the <tt>/WEB-INF/web.xml</tt> file we've mentioned before. Here's a basic example of
what it should look like if you're using <b>Tomcat</b>.
<div class="note">
Please note that you may not want to enable all developer support tools in a production environment.
</div>
</p>
<pre class="example">
<div class="example-header">maktest/WEB-INF/web.xml</div>
&lt;?xml version="1.0" encoding="utf-8"?&gt;

&lt;web-app xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4"&gt;

  &lt;!-- Makumba Controller Filter, needed to invoke e.g. form responders --&gt;
  &lt;filter&gt;
    &lt;filter-name&gt;makumba_controller&lt;/filter-name&gt;
    &lt;filter-class&gt;org.makumba.controller.http.ControllerFilter&lt;/filter-class&gt;
  &lt;/filter&gt;

  &lt;filter-mapping&gt;
    &lt;filter-name&gt;makumba_controller&lt;/filter-name&gt;
    &lt;url-pattern&gt;*.jsp&lt;/url-pattern&gt;
  &lt;/filter-mapping&gt;


  &lt;!-- Developer support - MDD & Business logic browser & viewer --&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;mddLinker&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.makumba.devel.SourceViewServlet&lt;/servlet-class&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;mddLinker&lt;/servlet-name&gt;
    &lt;url-pattern&gt;*.jspx&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;mddLinker&lt;/servlet-name&gt;
    &lt;url-pattern&gt;*.jspxp&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;mddLinker&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/dataDefinitions/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;mddLinker&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/classes/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;mddLinker&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/logic/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;


  &lt;!-- Developer support - query tool --&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;dataQuery&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.makumba.devel.DataQueryServlet&lt;/servlet-class&gt;
  &lt;/servlet&gt;
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;dataQuery&lt;/servlet-name&gt;
    &lt;url-pattern>/dataQuery/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;


  &lt;!-- Developer support - single data object viewer --&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;dataViewer&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.makumba.devel.DataObjectViewerServlet&lt;/servlet-class&gt;
  &lt;/servlet&gt;
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;dataViewer&lt;/servlet-name&gt;
    &lt;url-pattern>/dataView/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;


  &lt;!--  Developer support - data lister --&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;dataLister&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.makumba.devel.DataTypeListerServlet&lt;/servlet-class&gt;
  &lt;/servlet&gt;
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;dataLister&lt;/servlet-name&gt;
    &lt;url-pattern>/dataList/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;

  
  &lt;!--  Developer support - pointer value converter --&gt;
  &lt;servlet&gt;
    &lt;servlet-name&gt;dataValueConverter&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.makumba.devel.DataPointerValueConverter&lt;/servlet-class&gt;
  &lt;/servlet&gt;
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;dataValueConverter&lt;/servlet-name&gt;
    &lt;url-pattern>/valueConverter/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;


  &lt;servlet&gt;
    &lt;servlet-name&gt;invoker&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.apache.catalina.servlets.InvokerServlet&lt;/servlet-class&gt;
    &lt;init-param&gt;
      &lt;param-name&gt;debug&lt;/param-name&gt;
      &lt;param-value&gt;0&lt;/param-value&gt;
    &lt;/init-param&gt;
    &lt;load-on-startup&gt;2&lt;/load-on-startup&gt;
  &lt;/servlet&gt;
	
  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;invoker&lt;/servlet-name&gt;
    &lt;url-pattern&gt;/servlet/*&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;

&lt;/web-app&gt;
</pre>

<h4>&nbsp;Database configuration files</h4>

<p>Remember talking about the SQL engine. We assumed you were using MySQL. Let's further assume
that the database server runs on your computer, having the hostname <tt>localhost</tt> and that you'll be
using a database named <tt>maktest</tt> to store the tables for this application. For <b>Makumba</b>
to know where and how it should connect to the database you need to create a file named <tt>localhost_mysql_maktest.properties</tt>
and put it in your application's <i>CLASSPATH</i>, i.e. your <tt>/WEB-INF/classes</tt> folder.</p>

<div class="note">If you're running the MySQL server remotely the database configuration file will have a name like <tt>dbhost.yourdomain.org_mysql_maktest.properties</tt>.</div>

<p>This file will contain the username and password to connect to the database and a line that
instructs the <b>Makumba</b> engine to create or alter any needed table structure (you should
comment this out after creating the final table structures). Here's an example:</p>

<pre class="example">
<div class="example-header">maktest/WEB-INF/classes/localhost_mysql_maktest.properties</div>
# Database configuration file
# Offset for autoincremented ids
dbsv=10

# Username to connect to database
sql.user=test
# Password
sql.password=

# Allow Makumba to alter the table structure
alter#=true
</pre>

<div class="note">More information on what this file can contain is available <a
  href="SQL-drivers.html#ConfigProperties">here</a>.</div>

<p>As <b>Makumba</b> is able to work with multiple databases, you need to instruct it where to
get it's default settings from. This is done via the <tt>MakumbaDatabase.properties</tt> file, also
located in your <i>CLASSPATH</i>. In this case:</p>

<pre class="example">
<div class="example-header">maktest/WEB-INF/classes/MakumbaDatabase.properties</div>
#Default database
default=localhost_mysql_maktest
</pre>

<h3><a name="Data">&nbsp;</a>Data definitions</h3>

<p>In order to be able to manipulate information from a database <b>Makumba</b> needs to know
what this info looks like. For each table you're using you need to provide a data definition file.
We recommend putting these files in a special folder: <tt>WEB-INF/classes/dataDefinitions</tt> and
giving them an <i>*.mdd</i> extension. For example:</p>

<pre class="example">
<div class="example-header">maktest/WEB-INF/classes/dataDefinitions/Person.mdd</div>
# Person.mdd
# Description file for Person entity

name=not null char[32]  ; Name
age=not null int        ; Age
</pre>
<br>
<div class="note">More information on <a href="makumba-spec.html#Data_Description">Makumba Data Definitions</a></div>

<h3><a name="Example">&nbsp;</a>Example application</h3>

<p>Now we have anything we need to run the first <b>Makumba</b>-powered application. Let's
create an <tt>index.jsp</tt> file in our applications root folder:</p>

<pre class="example">
<div class="example-header">maktest/index.jsp</div>
&lt;%@page contentType="text/html"%&gt;
&lt;%@page pageEncoding="utf-8"%&gt;
&lt;html&gt;
&lt;head&gt;&lt;title&gt;Person list&lt;/title&gt;&lt;/head&gt;
&lt;body&gt;

&lt;%@taglib uri="http://www.makumba.org/presentation" prefix="mak" %&gt;

&lt;h1&gt;Persons&lt;/h1&gt;
&lt;mak:list from="Person p"&gt;
&nbsp;&nbsp;&lt;mak:value expr="p.name"/&gt;, &lt;mak:value expr="p.age"/&gt; &lt;br/&gt;
&lt;/mak:list&gt;

&lt;/body&gt;
&lt;/html&gt;
</pre>

<p>Now, if everything went right, running this should return a page with the text <i>Persons:</i>.
If you're getting an error check to see you've done everything right. Running this simple app should
have also created a table named <tt>person_</tt> in your <tt>maktest</tt> database. Add some records
into that table and run the application again. You should get a list of persons and ages.</p>

<div class="note">This example might look trivial, if you completed it we invite you to move
on to <a href="makumba-example.html">a more complex example</a>. You're all set now!</div>

<script type="text/javascript">
  makeFooter("$Id$");
</script>

</body>
</html>